Skip to content

Add a per-product documentation version selector#335

Open
miharp wants to merge 1 commit into
OpenVoxProject:masterfrom
miharp:docs/issue-325-version-selector
Open

Add a per-product documentation version selector#335
miharp wants to merge 1 commit into
OpenVoxProject:masterfrom
miharp:docs/issue-325-version-selector

Conversation

@miharp

@miharp miharp commented Jun 11, 2026

Copy link
Copy Markdown
Contributor

What

Adds a per-product documentation version selector at the top of the sidebar, driven
by _data/products.yml (introduced in #328).

For the current product it lists the versions (newest first), marks the one being
viewed, and badges the version that latest aliases — e.g. 9.x · 8.x (latest).

image

Design notes

  • Per-product, not global. The theme's built-in selector is a single global
    dropdown, which can't express per-product versions on a multi-product site, so
    this is a custom picker reading site.data.products.
  • Hidden until there's a choice. A product's picker only renders when it has 2+
    versions, so nothing shows on the site today (every product has one version) — it
    appears automatically at the first cutover. single_version products (OpenVox
    Containers) are always skipped.
  • Version-root links. Switching points at each version's root (e.g.
    /openvox/9.x/). The sidebar persists across Turbo navigation, so root links stay
    correct without per-page rewriting. Keeping the reader on the same page across a
    switch (path-preserving) would need per-navigation JS and is a possible follow-up.
  • Turbo-aware. syncVersionPicker (in layout_end.html, alongside the existing
    nav-group sync) shows the current product's picker and marks the active version on
    each turbo:frame-load, with a fallback to the latest-aliased version on
    /<product>/latest/ pages.

Validation

Verified against a local two-version test bed (OpenVox 8.x + a 9.0.0-alpha1 9.x),
then torn down:

  • Direct loads of /8.x/, /9.x/, and the /latest/ alias: correct active marking
    and latest badge.
  • Turbo navigation between products: the picker swaps to the right product and marks
    the active version (browser-tested).
  • OpenVox Containers (single_version) excluded.
  • With the current single-version state, no picker renders (no stray wrapper).

Part of #325.

Render a version picker at the top of the sidebar, driven by _data/products.yml.
For the current product it lists the versions (newest first), marks the one being
viewed, and badges the version that `latest` aliases. Version links point at each
version's root; switching is an infrequent, deliberate jump, and root links stay
correct in the theme's persistent (Turbo-navigated) sidebar without per-page
rewriting (keeping the reader on the same page across a switch is a possible later
enhancement).

- _includes/version-selector.html renders a block per qualifying product (2+
  versions, not single_version) so the picker survives Turbo navigation between
  products. The wrapper is only emitted when at least one product qualifies, so
  nothing shows while every product still has a single version.
- layout_end.html gains syncVersionPicker, which on each Turbo frame load shows
  the block matching the current collection and marks the active version (with a
  fallback to the `latest`-aliased version on /<product>/latest/ pages), mirroring
  the existing nav-group sync.
- custom.css styles the picker to match the theme.

Verified against a local two-version test bed (OpenVox 8.x + a 9.0.0-alpha1 9.x):
correct active marking and latest badge on direct loads of 8.x, 9.x and the latest
alias; correct group swap and active marking across Turbo navigation between
products; OpenVox Containers (single_version) excluded; and no picker rendered while
all products have one version.

Part of OpenVoxProject#325.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: Michael Harp <mike@mikeharp.com>
@miharp miharp force-pushed the docs/issue-325-version-selector branch from 241eac9 to 3f378d3 Compare June 12, 2026 10:39
@miharp miharp marked this pull request as ready for review June 12, 2026 11:28
@miharp miharp requested a review from a team as a code owner June 12, 2026 11:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant